SMODS.Atlas#

This class allows you to use custom spritesheets (“Atlases”) or replace existing ones. Your mod must be located in its own subdirectory of the Mods folder. The file structure should look something like this:

Mods
└──NegateTexturePack
 ├── NegateTexturePack.lua
 └── assets
  ├── 1x
  │   ├── BlindChips-negate.png
  │   ├── Jokers-negate.png
  │   └── boosters-negate.png
  └── 2x
   ├── BlindChips-negate.png
   ├── Jokers-negate.png
   └── boosters-negate.png

Note

Due to Balatro’s pixel smoothing setting, it requires both a single and double resolution image file. Since version 26.829.0 SMODS generates the missing assets automatically if provided, so only one of the resolutions is needed (keeping 1x is recommended). Note that older versions of SMODS might crash if the file for the mod’s icon is not found in both folders.

  • Required parameters:

    • key

    • px: the width of each individual sprite at single resolution, in pixels.

    • py: the height of each individual sprite at single resolution, in pixels.

    • path: the image file’s name, including the extension (e.g. 'Jokers-negate.png').

      • If you want to use different sprites depending on the selected language, you can also provide a table:

    path = {
 ['default'] = 'Jokers.png', -- use this for any languages not specified
 ['zh_CN'] = 'Jokers-zh-CN.png',
 ['ja'] = 'Jokers-ja.png',
}

  • Optional parameters (defaults):

    • prefix_config, dependencies (reference)

    • atlas_table = 'ASSET_ATLAS'

      • Use ASSET_ATLAS for non-animated sprites

      • Use ANIMATION_ATLAS for AnimatedSprites (see guide)

      • Use STATE_ATLAS for StateSprites (see guide)

      • Use ASSET_IMAGES for other images

    • frames: for animated sprites, you can provide the default number of frames of the animation. Each column shows one frame, and animations may wrap to the next row.

    • fps: for animated sprites, you can provide the default animation speed by frames per second. The global default value is 10 or G.ANIMATION_FPS.

    • sprite_args: for animated sprites, may contain default sprite_args arguments for created sprites. If a sprite_args table is passed to SMODS.create_sprite(), its arguments take priority if defined. (see guide for Animated/StateSprites)

    • raw_key: Set this to true to prevent the loader from adding your mod prefix to the key. Useful for replacing sprites from the base game or other mods.

    • language: Restrict your atlas to a specific locale. Useful for introducing localized sprites while leaving other languages intact.

    • disable_mipmap: Disable mipmap being applied to this texture. Might remove artifacts on smaller textures.

    • force_pixel: (Added in 26.829.0) Always load the 1x sprite and force pixel smoothing off for this atlas. Useful for lower resolution pixel art that looks odd with smoothing enabled.

Applying textures to cards#

For objects of any class that have a visual representation in-game, you can assign a sprite from your atlas by setting atlas to the key of your atlas and pos to the position of the sprite on this atlas ({ x = 0, y = 0 } refers to the top-left corner). hc_atlas and/or lc_atlas can also be set instead to assign different sprites between the High Contrast and Low Contrast settings. For floating sprites, similar to Legendary Jokers or The Soul, you can define a soul_pos for that sprite, which can contain a custom draw function for that sprite. Optionally, soul_atlas, hc_soul_atlas and/or lc_soul_atlas can be specified to change the atlas assigned to the floating sprite. (soul_atlas and variants were added in 1620a)

Example:

SMODS.Joker {
 key = 'my_joker',
 atlas = 'my_atlas',
 pos = { x = 1, y = 1 }, -- second row, second column
 soul_atlas = 'my_other_atlas',
 soul_pos = {
  x = 0 , y = 0 -- first row, first column
  draw = function(card, scale_mod, rotate_mod) -- omit this function if you want the default behaviour
   -- custom draw code
  end
 }
}